[deckhouse-cli] Add registry error diagnostics for d8 mirror#320
Merged
[deckhouse-cli] Add registry error diagnostics for d8 mirror#320
Conversation
- Classify 11 types of registry errors (EOF, TLS, auth, DNS, timeout, network, rate limit, server errors, image/repo not found, OCI artifacts) and show user-friendly diagnostics with possible causes and solutions - Detect errors via errors.Is/errors.As through go-containerregistry's error chain including multierrs from HTTPS/HTTP fallback - Output colored diagnostics to stderr only when TTY is detected, respecting NO_COLOR and FORCE_COLOR environment variables - Integration tests verify classification against real HTTP responses from httptest servers (no Docker required) Signed-off-by: Roman Berezkin <roman.berezkin@flant.com>
- Split monolithic registryerr into three packages: pkg/diagnostic (generic HelpfulError), pkg/registry/errdiag (registry classifier), pkg/registry/errmatch (flow-control matchers) - Each command classifies errors with its own domain classifier; root.go only catches HelpfulError via errors.As, preventing false diagnostics across unrelated commands - Extend OCI media type detection to cover all Deckhouse artifact types, not just Trivy - Unify Trivy error handling: errors propagate to Classify instead of being intercepted and replaced with a warning string in the pusher retry loop - Add typed transport.Error checks in errmatch with string fallback for HEAD responses - Guard against double classification in Classify via errors.As check Signed-off-by: Roman Berezkin <roman.berezkin@flant.com>
- Package is only used by mirror pull/push, no need to keep it in pkg Signed-off-by: Roman Berezkin <roman.berezkin@flant.com>
Signed-off-by: Roman Berezkin <roman.berezkin@flant.com>
- Classifier contains application-level advice (CLI flags, docs links) specific to mirror commands - Document classifier placement convention in README and doc.go Signed-off-by: Roman Berezkin <roman.berezkin@flant.com>
- Pull and push each have their own errdetect package with command-specific advice - Pull auth suggests --license and --source-login, push suggests --registry-login - Push references <registry> positional argument, pull references --source flag Signed-off-by: Roman Berezkin <roman.berezkin@flant.com>
Signed-off-by: Roman Berezkin <roman.berezkin@flant.com>
- Error matchers are only used by mirror commands, belong in internal - File names match function names: classify.go -> diagnose.go (better name for clarity in general) Signed-off-by: Roman Berezkin <roman.berezkin@flant.com>
- Display each wrapped error level on its own line with increasing indentation for easier root-cause identification - Walk errors.Unwrap() to extract per-level context instead of showing a single flattened message - Update doc examples in README.md and doc.go to reflect the chain format Signed-off-by: Roman Berezkin <roman.berezkin@flant.com>
- Each cause now carries its own solutions so the user sees actionable advice next to the relevant problem, not two disconnected lists - Add Suggestion type pairing Cause with Solutions in HelpfulError - Causes without solutions (e.g. "registry closed connection") render cleanly without empty arrows - Regroup all pull and push classifier suggestions into cause-solution pairs Signed-off-by: Roman Berezkin <roman.berezkin@flant.com>
Signed-off-by: Pavel Okhlopkov <pavel.okhlopkov@flant.com>
ldmonster
approved these changes
Apr 13, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
User-friendly diagnostics for registry errors in
d8 mirror pull/push. At the application/UI layer, known errors (TLS, DNS, auth, timeout, etc.) are diagnosed and shown with possible causes and actionable solutions.Demo
What it does
NO_COLOR)errors.Is/errors.Asthrough the full error chain, with string fallback for HEAD responsesHow HelpfulError flows
RunEcalls business logic, gets a regularerrorerrdetect.Diagnose(err)- if recognized, returns*HelpfulError; otherwise the original error is returned as-isroot.goroot.gocheckserrors.As(err, &helpErr)- if it's aHelpfulError, prints colored diagnostic with causes/solutions; otherwise prints the plain errorKey:
root.goknows nothing about specific errdetect packages. Any command can return aHelpfulError- it will be caught and formatted.Architecture
pkg/diagnostic/- genericHelpfulErrortype withFormat()for colored outputinternal/mirror/errmatch/- error matchers for flow control (IsImageNotFound,IsRepoNotFound)internal/mirror/cmd/pull/errdetect/- pull-specific error diagnostics (advises--license,--source-login)internal/mirror/cmd/push/errdetect/- push-specific error diagnostics (advises--registry-login,--registry-password)root.gocatches any*HelpfulErrorviaerrors.As- does not import any errdetect